<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "https://www.w3.org/TR/html4/loose.dtd">
<html lang="zh-CN"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta http-equiv="Content-Language" content="zh-CN"><link href="stylesheet.css" media="all" rel="stylesheet" type="text/css">
<title>制作文档</title>
<script> var _hmt = _hmt || []; (function() { var hm = document.createElement("script"); hm.src = "https://hm.baidu.com/hm.js?d286c55b63a3c54a1e43d10d4c203e75"; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(hm, s); })(); </script>
</head><body class="SECT1">
<div>
<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr><th colspan="5" align="center" valign="bottom">PostgreSQL 8.2.3 中文文档</th></tr>
<tr><td width="10%" align="left" valign="top"><a href="docguide-toolsets.html" accesskey="P">后退</a></td><td width="10%" align="left" valign="top"><a href="docguide.html">快退</a></td><td width="60%" align="center" valign="bottom">附录G. Documentation</td><td width="10%" align="right" valign="top"><a href="docguide.html">快进</a></td><td width="10%" align="right" valign="top"><a href="docguide-authoring.html" accesskey="N">前进</a></td></tr>
</table>
<hr align="LEFT" width="100%"></div>
<div class="SECT1"><h1 class="SECT1"><a name="DOCGUIDE-BUILD">G.3. 制作文档</a></h1>
<p>一旦把所有的东西都设置好了，进入目录 <tt class="FILENAME">doc/src/sgml</tt> 然后运行下面其中一条命令(记得要用 GNU make)：</p>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88297">G.3.1. HTML</a></h2>
<p>制作 HTML 版本的文档：</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake html</kbd></pre>
<p>这也是缺省目标。</p>
<p>在制作 HTML 文档的时候，这个过程同样生成用于索引条目的连接信息。因此，如果你希望文档在最后有索引，那么你需要制作一次 HTML 文档，然后再次把文档制作成你想要的格式。</p>
<p>为了便于最终版本的发布，包含 HTML 文档的文件被存储在一个 tar 包里，在安装的时候解包。要创建 HTML 文档包，使用下面的命令</p>
<pre class="PROGRAMLISTING">cd doc/src
gmake postgres.tar.gz</pre>
<p>在发布版里，这些文档包放在 <tt class="FILENAME">doc</tt> 目录里，并且缺省时 <tt class="COMMAND">gmake install</tt> 会安装这些东西。</p>
</div>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88310">G.3.2. 手册页</a></h2>
<p>用 <span class="APPLICATION">docbook2man</span> 工具把 DocBook 的 <code class="SGMLTAG">refentry</code> 页面转换成适于做手册页的 *roff 输出。这些手册页也是以 tar 归档的形式发布的，与 HTML 版本类似。要创建手册页包，用命令</p>
<pre class="PROGRAMLISTING">cd doc/src
gmake man.tar.gz</pre>
<p>这些命令最后会在 <tt class="FILENAME">doc/src</tt> 目录生成一个 tar 文件。</p>
<p>要生成高质量的手册页，可能必须使用一个修改过的版本的转换工具，或者做一些手工调整。所有手册页都应该在发布之前手工检查。</p>
</div>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88320">G.3.3. 用 <span class="APPLICATION">JadeTex</span> 生成的打印输出</a></h2>
<p>如果你想用 <span class="APPLICATION">JadeTex</span> 生成一个可打印的文档，可以用下面的命令：</p>
<ul>
<li><p>制作一个 DVI 版本</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake postgres.dvi</kbd></pre></li>
<li><p>从 DVI 里生成一个 Postscript </p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake postgres.ps</kbd></pre></li>
<li><p>制作一个 PDF</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake postgres.pdf</kbd></pre>
<p>然，你也可以从 Postscript 里制作 PDF 版本，但是如果你直接生成 PDF ，那么它会有超链接和其它增强的特性。</p></li>
</ul>
</div>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88346">G.3.4. 通过 RTF 生成打印输出</a></h2>
<p>你也可以通过把它转换成 RTF 并且用一个办公套件进行格式微调的办法把 PostgreSQL 文档转换成 RTF 格式的办法来创建一个可打印的版本。根据你使用的不同的办公套件，然后你就可以分别把文档转换成 Postscript 或者 PDF 。下面的步骤演示了使用 Applixware 实现的过程。</p>
<div class="NOTE">
<blockquote class="NOTE">
<p><b>【注意】</b>目前看来 PostgreSQL 的当前版本的文档碰到了 OpenJade 的大小限制的一些毛病。如果制作 RTF 版本的时候停住了好长时间，而输出文件还是 0 ，那么你很有可能碰到了这个毛病。不过，正常的制作要花 5 到 10 分钟，因此不要太快退出。</p>
</blockquote>
</div>
<div class="PROCEDURE">
<p><b>Applixware RTF 清理</b></p>
<p><span class="APPLICATION">OpenJade</span> 忽略了声明文本主体的缺省风格。以前，这个未经查明的问题导致目录生成的长时间处理。不过，在 Applixware 的工作人员的全力帮助下，这个病症被诊断出来并且找到了绕开的办法。</p>
<ol type="1">
<li class="STEP"><p>键入下面命令生成 RTF 版本：</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake postgres.rtf</kbd></pre></li>
<li class="STEP"><p>修复 RTF 文件，以正确声明所有风格，尤其是缺省风格。如果文档包含 <code class="SGMLTAG">refentry</code> 段，那么还必须把和前面的段落与当前段落绑定的格式化暗示替换为当前的段落和后面的段落绑定。在 <tt class="FILENAME">doc/src/sgml</tt> 里有一个 <tt class="COMMAND">fixrtf</tt> 用于完成这样的修补：</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">./fixrtf --refentry postgres.rtf</kbd></pre>
<p>该脚本把 <tt class="LITERAL">{\s0 Normal;}</tt> 增加为文档的零级风格。根据 Applixware ，RTF 标准会禁止增加一种隐含的零级风格，尽管 Microsoft Word 碰巧可以处理这种情况。为了修复 <code class="SGMLTAG">refentry</code> 段落，该脚本把 <tt class="LITERAL">\keepn</tt> 标记替换为 <tt class="LITERAL">\keep</tt></p></li>
<li class="STEP"><p>在 Applixware Words 里打开新的文档，然后输入该 RTF 文件。</p></li>
<li class="STEP"><p>用 Applixware 生成一个新的目录(ToC)。</p>
<ol class="SUBSTEPS" type="a">
<li class="STEP"><p>选择现有的 ToC 行，从第一行第一个字符到最后一行最后一个字符。</p></li>
<li class="STEP"><p>用 <span class="GUIMENU">Tools</span>-&gt;<span class="GUISUBMENU">Book Building</span>-&gt;<span class="GUIMENUITEM">Create Table of Contents</span> 制作一个新的 ToC 。选择头三层头用于包含在 ToC 里。这将用本地的 Applixware ToC 代替从 RTF 里输入进来的行。</p></li>
<li class="STEP"><p>使用 <span class="GUIMENU">Format</span>-&gt;<span class="GUIMENUITEM">Style</span> 调整 ToC 格式，选择每三种 ToC 风格，然后为 <tt class="LITERAL">First</tt> 和 <tt class="LITERAL">Left</tt> 调整边距。使用下面的值：
<div class="INFORMALTABLE"><a name="AEN88409"></a>
<table border="1" class="CALSTABLE"><col><col><col>
<thead>
<tr><th>风格</th><th>第一边距(英寸)</th><th>左边距(英寸)</th></tr>
</thead>
<tbody>
<tr><td><tt class="LITERAL">TOC-Heading 1</tt></td><td><tt class="LITERAL">0.4</tt></td><td><tt class="LITERAL">0.4</tt></td></tr>
<tr><td><tt class="LITERAL">TOC-Heading 2</tt></td><td><tt class="LITERAL">0.8</tt></td><td><tt class="LITERAL">0.8</tt></td></tr>
<tr><td><tt class="LITERAL">TOC-Heading 3</tt></td><td><tt class="LITERAL">1.2</tt></td><td><tt class="LITERAL">1.2</tt></td></tr>
</tbody>
</table>
</div></P></li>
</ol></li>
<li class="STEP"><p>对文档进行加工：</p>
<ul>
<li><p>调整分页符</p></li>
<li><p>调整表列宽</p></li>
</ul></li>
<li class="STEP"><p>用正确的值替换 ToC 里例子和图片部分右对齐的页数。这些对每个文档只需要花几分钟。</p></li>
<li class="STEP"><p>如果索引是空的，那么从文档中删除它。</p></li>
<li class="STEP"><p>重新生成并调整目录。</p>
<ol class="SUBSTEPS" type="a">
<li class="STEP"><p>选择 ToC 字段</p></li>
<li class="STEP"><p>选择 <span class="GUIMENU">Tools</span>-&gt;<span class="GUISUBMENU">Book Building</span>-&gt;<span class="GUIMENUITEM">Create Table of Contents</span></p></li>
<li class="STEP"><p>通过选择 <span class="GUIMENU">Tools</span>-&gt;<span class="GUISUBMENU">Field Editing</span>-&gt;<span class="GUIMENUITEM">Unprotect</span> 解除 ToC</p></li>
<li class="STEP"><p>删除 ToC 中的第一行，它是指向 ToC 本身的一条记录。</p></li>
</ol></li>
<li class="STEP"><p>把该文档保存为 Applixware Words 本地文档格式以便于最后的编辑。</p></li>
<li class="STEP"><p>把该文档以 Postscript 格式"打印"到一个文件。</p></li>
</ol>
</div>
</div>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88474">G.3.5. 纯文本文件</a></h2>
<p>有好几个文件是以纯文本的模式发布的，主要是为了在安装过程中阅读。<tt class="FILENAME">INSTALL</tt> 文件对应<a href="installation.html">章14</a>，只有一点用于不同环境的修改。要创建这个文件，进入目录 <tt class="FILENAME">doc/src/sgml</tt> 然后敲入 <kbd class="USERINPUT">gmake INSTALL</kbd> 。这样就会创建一个叫 <tt class="FILENAME">INSTALL.html</tt> 的文件，你可以用 Netscape Navigator 把它另存为一个文本文件，然后把它拷到现存文件的位置。好像 Netscape 提供了最高的 HTML 到文本的转换质量(比 <span class="APPLICATION">lynx</span> 和 <span class="APPLICATION">w3m</span> 好)。</p>
<p>文件 <tt class="FILENAME">HISTORY</tt> 可以用类似方法创建，用的命令是 <kbd class="USERINPUT">gmake HISTORY</kbd> 。对于 <tt class="FILENAME">src/test/regress/README</tt> 文件，命令是 <kbd class="USERINPUT">gmake regress_README</kbd> 。</p>
</div>
<div class="SECT2"><h2 class="SECT2"><a name="AEN88492">G.3.6. 语法检查</a></h2>
<p>制作文档可能需要很长时间。但是有一个方法用于只检查文档文件的语法正确性，只要花几秒钟：</p>
<pre class="SCREEN"><samp class="PROMPT">doc/src/sgml$ </samp><kbd class="USERINPUT">gmake check</kbd></pre>
</div>
</div>
<div>
<hr align="LEFT" width="100%">
<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr><td width="33%" align="left" valign="top"><a href="docguide-toolsets.html" accesskey="P">后退</a></td><td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">首页</a></td><td width="33%" align="right" valign="top"><a href="docguide-authoring.html" accesskey="N">前进</a></td></tr>
<tr><td width="33%" align="left" valign="top">工具集</td><td width="34%" align="center" valign="top"><a href="docguide.html" accesskey="U">上一级</a></td><td width="33%" align="right" valign="top">文档写作</td></tr>
</table>
</div>
</body></html>